Shell Plug-Ins (OD PG)

Inside Macintosh: OpenDoc Programmer's Guide / Part 2 - Programming: Chapter 10 - Extending OpenDoc

Shell Plug-Ins
You can extend the capabilities of the document shell or add session-wide functionality to OpenDoc by implementing shell plug-ins. Shell plug-ins are shared libraries rather than subclasses of ODExtension. A shell plug-in is not associated with any particular part object. Your shell plug-in must be installed on the user's machine when a document first opens, if it is to be used with that document.
You can create shell plug-ins for any of several purposes, including these:

to install a dispatch module or focus module that will be available to all parts in the document
to install an object (such as a spelling checker) into a name space, allowing it to be accessed as a service by all parts in the document
to replace parts of OpenDoc with your own capabilities, from individual objects (see "Patching OpenDoc," next) to entire subsystems (see "Runtime Object Relationships")

A shell plug-in has a single exported entry point to OpenDoc: its installation function. Your plug-in library needs to implement only that function, with this interface:
OSErr ODShellPluginInstall(Environment* ev, 
                           ODDraft* draft, 
                           ODShellPluginActionCodes* action );
The installation function must have exactly the specified name as well as the specified parameters and return value. You must ensure that the function name ODShellPluginInstall appears in your library's list of exported symbols.
The draft parameter specifies the document draft that is being opened. Use the action parameter to return a value specifying whether the document shell should maintain a connection to your shell plug-in library after the installation function completes.
The installation function must always return noErr, unless it cannot execute. For any ODShellPluginInstall function that returns an error, OpenDoc displays a dialog box to the user requesting that the shell plug-in be removed from the user's system.
Your shell plug-in must follow the conventions for shared libraries. On the Mac OS platform, it should have the file type 'shlb' so that the Code Fragment Manager can recognize it as an import library, and it can optionally have the initialization and termination entry points available to import libraries. (Its expected main entry point is replaced by the ODShellPluginInstall function.) For more information on shared library structure, see Inside Macintosh: PowerPC System Software.
Execution of a shell plug-in happens like this:

Whenever the user opens an OpenDoc document, OpenDoc launches the document shell. The document shell initializes itself and the session object, and gains access to the document's current draft.
The document shell then accesses each plug-in library and calls its ODShellPluginInstall function. The ODShellPluginInstall function performs the functions the plug-in is designed for: it installs custom focus modules or dispatch modules, it patches session-level objects, or it otherwise modifies shell functionality. ODShellPluginInstall then returns the appropriate OSErr value and exits.
After all plug-ins have executed, the root part of the OpenDoc document opens the document window.

If it is to be executed, your shell plug-in file must be located in the OpenDoc Shell Plug-Ins folder on the user's system. See Appendix C, "Installing OpenDoc Software and Parts", for more information.
The document shell must look at all entries in your shell plug-in file's code-fragment ('cfrg') resource for a valid entry point before dismissing the file. For this reason, the Code Fragment Manager loads every single fragment into memory. This is a time-consuming operation; however, you can make it more efficient by taking these steps:

Make the first 'cfrg' entry in your shell plug-in file refer to the fragment containing the entry point.
Try to avoid putting anything but plug-ins in the OpenDoc Shell Plug-Ins folder.